home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / editor / editor2 / hsc.lha / hsc / src_docs / fileargs.hsc < prev    next >
Text File  |  1996-11-10  |  5KB  |  142 lines
  1. <WEBPAGE chapter="hsc - " title="File Options"
  2.     PREV="index.html" NEXT="copy.html">
  3.  
  4. There are several CLI options that specify where <hsc> should take
  5. the input from and where the output should be placed. This section
  6. describes the differences and (dis-)advanteges.
  7.  
  8. <H2>Converting single files</H2>
  9.  
  10. This one uses a single file for input and output:
  11. <PRE>
  12.     hsc FROM hugo.hsc TO hugo.html
  13. </PRE>
  14. It will use <FILE>hugo.hsc</FILE> and outputs to <FILE>hugo.html</FILE>.
  15. Both input and output will be located in the current directory. This can
  16. be useful if you only want to quickly process a single file trough <hsc>,
  17. and do not want to set up a complete project.
  18.  
  19. <H2>Using different directories for input and output</H2>
  20.  
  21. <P>One of the features of <hsc> is that your object can be located at
  22. a totally different place from the source. This enables you to
  23. place your sources at a different disk as the one the WebServer
  24. has access to, saving server space.</P>
  25.  
  26. For instance, you can use
  27. <PRE>
  28.     hsc FROM hugo.hsc TO www:sepp/hugo.html
  29. </PRE>
  30.  
  31. <P>to use <FILE>hugo.hsc</FILE>, located in the current direcory, and
  32. create <FILE>www:sepp/hugo.html</FILE>. Note that all images,
  33. other documents etc. you reference fromout <FILE>hugo.hsc</FILE> using
  34. relative URIs have to be located at the corresponding place within
  35. the directory <FILE>www:sepp/</FILE>.</P>
  36.  
  37. <P>For example, if <FILE>hugo.hsc</FILE> contains a tag
  38. <$source pre>
  39.     <IMG SRC="image/back.gif" ALT="back">
  40. </$source>
  41. the image file <FILE>back.gif</FILE> will have to be located at
  42. <FILE>www:sepp/image/back.gif</FILE>.
  43.  
  44. <H2>Using a destination directory</H2>
  45.  
  46. The same as above can be performed using
  47. <PRE>
  48.      hsc FROM hugo.hsc TO www:sepp/
  49. </PRE>
  50. <P>Note the trailing slash that tells <hsc> that it should now output
  51. to a directory and determine the filename by itself. Usually, it
  52. will use <CODE>(input filenname, without ".hsc", but a ".html"
  53. appened)</CODE>, resulting into <FILE>www:sepp/hugo.html</FILE>
  54. as before. You can change this using the CLI option 
  55. <op_extension>.</P>
  56.  
  57. <H2>Using sub directories</H2>
  58.  
  59. <P>For complex project, usually not all documents are located at the
  60. same directory. For example, <FILE>hugo.hsc</FILE> is no more
  61. placed in the current directory, but in 
  62. <FILE>people/hugo.hsc</FILE>.</P>
  63.  
  64. Invoking hsc like
  65. <PRE>
  66.     hsc FROM people/hugo.hsc TO www:sepp/
  67. </PRE>
  68. <P>will now ouput to <FILE>www:sepp/people/hugo.html</FILE>. Note that you
  69. have to take care that the directory <FILE>www:sepp/people/</FILE>
  70. exists, <hsc> will not create any new directories by itself.</P>
  71.  
  72. <P>If you now want to embed an image located at 
  73. <FILE>www:sepp/image/back.gif</FILE>, you have to use
  74. <$source pre>
  75.     <IMG SRC="../image/back.gif" ALT="back">
  76. </$source>
  77. Alternatively, you can use and <fe_absuri>:
  78. <$source pre>
  79.     <IMG SRC=":image/back.gif" ALT="hugo">
  80. </$source>
  81.  
  82. Another way to obtain the same result is using
  83. <PRE>
  84.     hsc FROM people/hugo.hsc TO www:sepp/people/hugo.html
  85. </PRE>
  86. <P>In this case, <hsc> is smart enough to figure out that the
  87. destination directory is <FILE>www:sepp/</FILE>, and you
  88. are using <FILE>people/</FILE> as subdirectory.</P>
  89.  
  90. But if you try to use
  91. <PRE>
  92.     hsc FROM people/hugo.hsc TO www:sepp/stuff/hugo.html
  93. </PRE>
  94. <hsc> can not figure out what to use as destination- or
  95. subdirectory, and will show up an error message:
  96. <PRE>
  97.     unmatched corresponding relative directories:
  98.       input  `people/'
  99.       output `stuff/'
  100. </PRE>
  101. In this case, you will have to rename your directories.
  102.  
  103. <H2>Using pipes</H2>
  104.  
  105. <P>Short: It is possible to use pipes with <hsc>, but it should be
  106. avoided in most cases; <hsc> isn't really <qq>pipable</qq>. It does not 
  107. continuously read data from the input and write parts of the output.</P>
  108.  
  109. <P>(<Technote>It reads the whole
  110. input file with a single call to <CODE>fread()</CODE>, creates the
  111. output in memory and writes it with (more or less) a single 
  112. <CODE>fwrite()</CODE>. The main reasons why it works this way are:
  113. I hate to check for I/O errors, <CODE>fungetc()</CODE> usually does not
  114. work after a linefeed and
  115. memory mapped files are not supported by the standard ANSI library.)</P>
  116.  
  117. <P>Additionally, it impossible for <hsc> to maintain a project file
  118. without knowledge of the filenames for document and source, so 
  119. several features will be disabled.</P>
  120.  
  121. <P>If <hsc> needs to access relative URIs, it will have to use the
  122. current directory as starting point.</P>
  123.  
  124. <P>Therefor, pipes should only be used if you quickly want to test
  125. a feature on a single file or something like that.</P>
  126.  
  127. Anyway, here is an example:
  128.  
  129. <PRE>    hsc STDIN</PRE>
  130.  
  131. This specifies the (case sensitive) pseudo-filename <KBD>STDIN</KBD> 
  132. as input, which will use <stdin>. 
  133. Missing a <KBD>TO</KBD> option, the output will be written to <stdout>.
  134. Now using this like
  135.  
  136. <$source PRE>    hsc STDIN <hugo.hsc >hugo.html</$source>
  137.  
  138. would be equal to
  139. <PRE>    hsc hugo.hsc TO hugo.html</PRE>
  140. Again: Try to avoid this.
  141. </WEBPAGE>
  142.